<html>
<!-- (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Hewlett-Packard Development Company, LP -->
<head>
<title>Jena2 Derby HowTo</title>
<link href="../styles/doc.css" rel="stylesheet" type="text/css" />
</head>
<body>

<h1>HowTo Use Apache Derby with Jena2</h1>

<h2>What is HSQLDB?</h2>

<p><a href="http://db.apache.org/derby/">Apache Derby</a> is a relational 
database implemented entirely in Java. Used with Jena, it provides a 
convenient way to give persistence to RDF data by using it as an embedded 
database engine, within the 
application JVM and storing data in the local file system. No database server 
need be run. Derby can also be run as a shared server.</p>

<h2>Download and Installation of Apache Derby</h2>

<p>Download Apache Derby, install and put <code>derby.jar</code> 
file on the application classpath. This includes the JDBC driver and the 
database engine.</p>

<h2>Connecting Your Jena Program to Apache Derby</h2>
<h3>JDBC URLs</h3>
<p>JDBC URLs for Derby look like <code>jdbc:derby:<i>datbasename</i>.&nbsp;
</code>The use of parameter <code>&quot;create=true&quot;</code> causes a database to be 
created if it does not already exist -- <code>jdbc:derby:<i>datbasename;create=true</i></code>. 
For embedded use, the user name and password can both be &quot;&quot;.</p>
<p>The database JDBC driver controls whether the embedded or server mode is in 
operation (unlike HSQLDB where the URl changes but the driver is the same). The 
driver is class <code>org.apache.derby.jdbc.EmbeddedDriver</code> for embedded 
use (no separate server) or <code>org.apache.derby.jdbc.ClientDriver</code>.</p>
<p>The Jena driver name is &quot;Derby&quot;.</p>
<p>Persistent models are <a href="creating-db-models.html">created</a> in the 
same way for any database system: </p>
<blockquote>
  <ol>
    <li>Load the JDBC driver. This enables the Jena program to communicate with 
    the database instance.</li>
    <li>Create a database connection. This creates a Java object for a database 
    connection.</li>
    <li>Create a ModelMaker for the database</li>
    <li>Create a Model for existing or new data.</li>
  </ol>
</blockquote>

<p>These steps are illustrated in the following Java code.</p>

<pre class="box">
String className = &quot;org.apache.derby.jdbc.EmbeddedDriver&quot;;   // path of driver class
Class.forName (className);                                   // Load the Driver
String DB_URL =    &quot;<code>jdbc:derby:<i>database</i></code>&quot;;                    // URL of database 
String DB_USER =   &quot;&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;                // database user id
String DB_PASSWD = &quot;&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;               // database password
String DB =&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;Derby&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;              // database type

// Create database connection
IDBConnection conn = new DBConnection ( DB_URL, DB_USER, DB_PASSWD, DB );
ModelMaker maker = ModelFactory.createModelRDBMaker(conn) ;

// create or open the default model
Model model = maker.createDefaultModel();

// Close the database connection
conn.close();
</pre>
    
<h2>Apache Derby Notes</h2>
<p>When used embedded, only one application can attach to the database at a 
time.</p>
<p>The default transaction level is TRANSACTION_READ_COMMITTED, means that 
overlapping transactions do not read uncomitted updates but do see comitted 
updates as soon as one transaction commits. Derby supports other modes - see the 
Derby documentation and the javadoc for <code>java.sql.Connection</code>.</p>
<p>The application can 
use locking within the application, such as <a href="../how-to/concurrency.html">MRSW 
locking</a>, or provide it's own locking, to ensure that updates and reads do not overlap.</p>


</body>
</html>
